Document that Future callbacks are not reentrant-safe

[TheBlueMatt]

Claude was complaining about this, and it seems worth documenting, but not worth (and kinda hard to) fix.

[ldk-reviews-bot]

I've assigned @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[ldk-claude-review-bot]

I've reviewed the full diff and examined the surrounding code in lightning/src/util/wakers.rs to understand the reentrancy constraints being documented.

The documentation additions are accurate: complete_future (line 141-156) calls callback.call() while holding the FutureState mutex lock, and is itself called from Notifier::notify while holding the notify_pending lock. Re-entering either Future or Notifier from a callback would deadlock.

No issues found.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.09%. Comparing base (1ff1bb4) to head (b06ba3f).
⚠️ Report is 120 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4535      +/-   ##
==========================================
- Coverage   87.12%   87.09%   -0.03%     
==========================================
  Files         163      163              
  Lines      108740   108740              
  Branches   108740   108740              
==========================================
- Hits        94735    94708      -27     
- Misses      11520    11546      +26     
- Partials     2485     2486       +1     

Flag	Coverage Δ
fuzzing	40.20% <ø> (-0.01%)	⬇️
tests	86.19% <ø> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.