architecture: define gateway capabilities before adding more providers

[teesofttech]

Why

IPaymentGateway currently requires create, verify, and refund for every provider, even when a provider or payment method does not support the same lifecycle. Adding more providers will multiply NotImplementedException paths and inaccurate documentation.

Scope

• Write an ADR for capability modeling and provider API versioning.
• Model optional operations, currencies, countries, payment methods, redirect/direct flows, asynchronous states, webhooks, refunds, and saved methods.
• Decide how routing consumes capabilities.
• Define compatibility rules for adding enum values and interface members.
• Generate documentation/UI discovery from the same metadata.

Acceptance criteria

• Unsupported operations are discoverable without invoking them.
• No adapter needs a fake implementation merely to satisfy the interface.
• Routing filters by capabilities.
• Docs and demo UI consume the same source of truth.
• ADR includes migration and semantic-versioning impact.