docs: document when each ContractError variant is returned (#698)

[ayomidearegbeshola29-dev]

Add doc-comments explaining when each ContractError variant is returned

Summary

Closes #698

Every variant of the unified ContractError taxonomy
(contracts/split/src/error.rs) now carries a /// doc comment that explains
when the contract returns it. Previously ~21 variants (discriminants 1–18,
23, 24, 25) had no documentation, which made the error taxonomy hard to use
for contributors wiring up new failure paths and for integrators mapping error
codes.

The comments follow the existing convention already used by the documented
variants: a one-line /// description of the trigger condition, referencing
the originating issue where applicable (e.g. /// Issue #330: ...).

What changed

• Added doc comments to the previously-undocumented variants:
  NotAuthorized, InvoiceNotFound, DeadlinePassed, AlreadyFunded,
  InvalidAmount, InvoiceFrozen, InvalidStatus, PayerNotAllowed,
  FundingInsufficient, OracleCallFailed, NotArbiter, NotDisputed,
  AlreadyExecuted, TimelockPending, ContractPaused, InvalidRecipients,
  PrerequisiteNotMet, BatchLimitExceeded, InvalidRating, AlreadyRated,
  RateLimitExceeded.
• Discriminants and ordering are untouched (they are part of the stable
  on-chain error-code contract), so this is a non-breaking documentation-only
  change.

Verification

This is a documentation-only change; no code paths changed. Doc comments do not
affect compilation, so existing builds/tests are unaffected by the content.
(Note: cargo check on main currently fails for an unrelated, pre-existing
reason — a malformed duplicate invoice_expired in events.rs. That is tracked
separately and is not introduced by this PR.)

Notes for reviewers

• Comments describe the trigger condition ("when it is returned"), matching
  the issue's acceptance criterion, rather thanrestating the variant name.
• Where the trigger was unambiguous from the name + surrounding code I kept the
  comment concise; where it depended on a feature flag or list (e.g.
  PayerNotAllowed ↔ allowed_payers) I called that out.

closes #698

[ayomidearegbeshola29-dev]

Re-homed: PR now opened from assignee account gabrielujelistic-collab (replacement #728-#731).