Clarify and Unify event handling documentation

[TheBlueMatt]

We should clean up the event handling documentation so that it much more clearly describes what the downstream requirements are, plus move them into one place and cross-link instead of having different requirements spewed across several different locations.

[MaxFangX]

This is the doc comment I just wrote above our handle_event method - feel free to edit / use as source material

/// Event handling requirements:
///
/// - The handling of an event must *complete* before returning from this
///   function. Otherwise, if the channel manager gets persisted and the the
///   program crashes ("someone trips on a cable") before event handling is
///   complete, the event will be lost.
/// - Event handling must be *idempotent*. It must be okay to handle the
///   same event twice, since if an event is handled but the program crashes
///   before the channel manager is persisted, the same event will be emitted
//    again.
/// - The event handler must avoid reentrancy by not making direct calls to
///   [`ChannelManager::process_pending_events`] or
///   [`ChainMonitor::process_pending_events`], otherwise there may be a
///   deadlock.
///
/// [`EventsProvider`]: lightning::util::events::EventsProvider
/// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
/// [`ChainMonitor`]: lightning::chain::chainmonitor::ChainMonitor

In plaintext:

Event handling requirements:

• The handling of an event must complete before returning from this function. Otherwise, if the channel manager gets persisted and the the program crashes ("someone trips on a cable") before event handling is complete, the event will be lost.
• Event handling must be idempotent. It must be okay to handle the same event twice, since if an event is handled but the program crashes before the channel manager is persisted, the same event will be emitted again.
• The event handler must avoid reentrancy by not making direct calls to ChannelManager::process_pending_events or ChainMonitor::process_pending_events, otherwise there may be a deadlock.