Write the Events Reference

[codebestia]

Events are the protocol's off-chain integration surface. Document every event emitted by the contracts, its topics, its data payload, and the operation that triggers it, so indexers and webhook consumers can be built reliably.

Proposed steps:

• Create docs/reference/events.md.
• For every event defined in contracts/shade/src/events.rs (and the events modules of account and the other crates), document: event name, topic tuple, data payload fields with types, the function that emits it, and when in that function it fires.
• Group events by domain and provide an index.
• Document the topic conventions used for filtering, and give example filters for the most common subscriptions (all payments for one merchant, all status changes for one invoice).
• Document ordering and atomicity guarantees: events from a reverted transaction are never observed; multiple events from one call arrive in emission order.
• Provide a worked example of decoding one event with the Stellar SDK.

Acceptance criteria:

• docs/reference/events.md exists and covers every event emitted across the workspace.
• Topics and data payloads are documented accurately against the source.
• Filtering examples are provided for common indexing use cases.
• Ordering and revert semantics are stated.