prep for reload/raastas part 3: add GST notice, max and min values and make contact picker and contacts page behave correctly for fahipay contacts

docs/thijooree/20-transfer-flows.md

@@ -10,7 +10,7 @@ The transfer screen (`TransferFragment`) handles all outgoing payments across MI
 
 | Factory method | Behaviour |
 |---|---|
-| `newInstance(accountNumber, displayName, subtitle, colorHex, imageHash)` | Pre-fills the "To" card from a contact, recents pick, or About → Donate |
+| `newInstance(accountNumber, displayName, subtitle, colorHex, imageHash, contactCategory?)` | Pre-fills the "To" card from a contact, recents pick, or About → Donate. A Fahipay favourite's `contactCategory` opens it as that payout service instead (see [Saved Fahipay favourites](#saved-fahipay-favourites)) |
 | `newInstanceFrom(account: BankAccount)` | Pre-selects the given account in the "From" dropdown |
 | `newInstanceFromQr(accountNumber, displayName, amount, remarks, fromAccountNumber?)` | Pre-fills recipient + optional amount/remarks from a PayMV QR scan |
 | `newInstanceFromBmlQr(qrUrl, fromAccountNumber?)` | BML card/gateway/POS QR merchant payment mode — locks recipient, may pre-fill amount |
@@ -90,6 +90,51 @@ The result maps to one or more Fahipay services:
 
 The matching services are offered in the Transfer Type picker (see above).
 
+#### Saved Fahipay favourites
+
+Each Fahipay favourites list is one payout service (`FahipayService.contactCategory` / `fromContactCategory`):
+
+| Contact category | Service |
+|---|---|
+| `FAHIPAY_RAASTAS` | Raastas |
+| `FAHIPAY_RELOAD` | Dhiraagu Reload |
+| `FAHIPAY_OOREDOO_BILL` | Ooredoo Bill Pay |
+| `FAHIPAY_DHIRAAGU_BILL` | Dhiraagu Bill Pay |
+
+So picking a favourite skips the carrier lookup and the picker. That service is offered as the only transfer type, so it's picked straight away (`TransferFragment.applyFahipayContact`). As with a searched number, that switches the source to the Fahipay wallet and applies the service's amount rules. This happens wherever a favourite is picked:
+
+- the contact picker sheet (the row's category goes back as `ContactPickerSheetFragment.KEY_CATEGORY`)
+- the "To" field's search-as-you-type dropdown
+- the Contacts page: the row's transfer button and the contact details sheet's Transfer action. Fahipay favourites have `canTransfer` set when their category maps to a service.
+
+Recents work the same way. Paying a number as a Fahipay service saves the recent with that service's category (`RecentPick.contactCategory`). The picker passes it back like a favourite's, so picking the recent pays with the same service. Recents saved before this was added have no category and are still filled in directly.
+
+#### Amount rules
+
+Each service has its own limits on the amount (`FahipayService.minAmount` / `maxAmount` / `decimalsAllowed`):
+
+| Service | Min (MVR) | Max (MVR) | Decimals |
+|---|---|---|---|
+| Raastas | 11 | no limit | no |
+| Ooredoo Bill Pay | 10 | 50,000 | yes, up to 2 places |
+| Dhiraagu Reload | 8 | 1,000 | no |
+| Dhiraagu Bill Pay | 10 | 5,000 | no |
+
+The amount is checked as the user types (`FahipayTransferHandler.amountProblem`). An amount that breaks a rule shows an error on the amount field ("Minimum is MVR 11", "Maximum is MVR 5,000", "Whole amounts only, no decimals", "Up to 2 decimal places"), and Send stays disabled. A trailing `.00` counts as a whole number. Services that don't take decimals switch the amount field to a number-only keypad.
+
+#### GST (Raastas)
+
+Raastas charges 8% GST out of the amount paid (`FahipayService.gstPercent`), so the number credited is less than the amount deducted from the wallet. The amount is GST-inclusive, so the credit is `amount / 1.08`, rounded down to 2 decimal places. The amount field's helper text says so:
+
+- Empty field: "8% GST is deducted from this amount"
+- With an amount: "Recipient receives MVR 92.59 after 8% GST" (for MVR 100)
+
+When the amount breaks a rule, the error replaces the helper text.
+
+#### Reference
+
+None of the Fahipay services take a reference. Picking one clears the Reference field and disables it, the same way BML merchant QR payments do. Clearing the service turns the field back on.
+
 ### BML source
 
 1. If the input type is `MIB_ACCOUNT`, calls `BmlValidateClient.verifyMibAccount()`.
@@ -281,6 +326,7 @@ The transfer button is only enabled when all of the following are true:
 - A recipient is resolved (`resolvedAccountNumber` not blank, or the BML handler's `qrInfo` is set)
 - Amount is greater than `0`
 - If transfer types are on offer, one has been picked
+- For a Fahipay service, the amount meets that service's rules (see [Amount rules](#amount-rules))
 - No connectivity error for `NO_INTERNET` or for the source bank
 
 ---