docs: refund limitation + remaining 3.1.0 race residual

CHANGELOG.md

@@ -133,6 +133,16 @@ what was requested.
   D9/R2.8) — not fixed by this settlement-gate work, which only changed the
   webhook's *retry* semantics (transient vs. permanent), not its order-lookup
   logic.
+- The reference-to-order binding introduced above closes the *sequential*
+  version of "one charge settles two orders" but is a read-then-write check
+  with no lock: two verifications racing at the exact same instant, for a
+  reference not yet bound to anything, can still both pass the check before
+  either saves. Reference-keyed locking (tracked as a corrected R2.4) is not
+  implemented in this release.
+- A verified, registered payment is not refundable through Magento's own
+  Credit Memo action — refunds must be issued directly from the Paystack
+  dashboard. This is a pre-existing gap, not introduced by this release; see
+  the User Guide's Refunds section.
 
 ### Upgrade note
 If a store's checkout was relying (unknowingly) on under- or mis-paid

marketplace/src/user-guide.md

@@ -76,6 +76,12 @@ Holding the confirmation email until payment is verified means customers are nev
 
 If verification does not complete — the customer closed the browser, or the network dropped — the webhook confirms the payment independently and moves the order forward.
 
+## Refunds
+
+A verified order shows its payment on the order (paid amount, invoice, transaction reference), but Magento's own **Credit Memo** / refund action is not available for Paystack orders — the extension does not submit refunds back through Magento.
+
+To refund a customer, issue the refund directly from your Paystack dashboard (or via Paystack's API). The Magento order itself is not updated automatically when you do this; add an order comment noting the refund if you want it visible on the order in Magento.
+
 ## Troubleshooting
 
 **Paystack does not appear at checkout.** Confirm **Enabled** is *Yes*, that both the public and secret key are filled in for the current mode, and that the order total falls between your configured minimum and maximum. Then run `php bin/magento cache:flush`.