NEW Option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS: enter the real amounts on multicurrency payments

[Pichinov-Jose]

What this solves

On a payment for an invoice in a foreign currency, Dolibarr derives one of the two amounts (company currency / invoice currency) from the other at the invoice rate. The amount really paid in the company currency almost always differs from that derivation — the bank applies its own rate on the day of the transfer — so the recorded payment does not match the bank statement, and the reconciliation carries a phantom difference.

What it adds

Everything is gated by a new option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS (off by default — behaviour is strictly unchanged without it).

1. Payment pages (customer and supplier): both the amount in the invoice currency and the real amount in the company currency can be entered; a read-only exchange rate derived live from the two amounts is displayed.
2. Paiement::create() / PaiementFourn::create(): when both amounts are provided for an invoice, keep them as entered (no derivation), derive the per-invoice exchange rate and store it on the dispatch line. An error is raised when the two amounts have opposite signs, a non-blocking warning when the derived rate differs by more than 50% from the invoice rate (probable swap of the two fields).
3. Paid status decided on the balance in the invoice currency: settled at the real amounts, a multicurrency invoice keeps a residual amount in company currency — that residual is the exchange-rate difference, it must not keep the invoice open.
4. Display: in the payments table of the invoice card, each payment shows a sub-line with the amount in the invoice currency and the real rate of that payment (multicurrency_amount / amount), so a rate different from the invoice rate is visible at a glance. The payment tooltip (customer and supplier) and the supplier invoice tooltip show the same information (amount in the invoice currency, rate).
5. A posteriori fix: a payment whose foreign amount is missing (recorded before the option, or by an import) can be completed from the payment card — gated by the hidden option MULTICURRENCY_PAYMENT_ALLOW_EDIT_REAL_AMOUNT plus admin rights.

Relationship with #38972 (@lvessiller)

The merged fix #38972 stores the invoice currency code/rate on the dispatch line when the caller does not fill the arrays. This PR integrates with it: in real-amounts mode the per-invoice derived rate is set into $this->multicurrency_tx[$key], which that fallback then naturally respects; without the option, the fallback behaviour is unchanged.

Compatibility

• Option unset ⇒ every code path falls back to the current behaviour (derivation at the invoice rate).
• No schema change: the payment dispatch tables already carry multicurrency_amount / multicurrency_tx.
• Follow-up PRs (deposits/credit notes carrying the invoice currency NEW Deposits and credit notes carry the invoice currency (option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS) #39666, exchange-difference display NEW Show the exchange difference and allow re-aligning the invoice rate (option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS) #39667) build on this option and are submitted separately to keep reviews small. The accounting booking of the exchange difference (666/766, timing, lettering) is a further step we want to design with the accountancy maintainers — see the dedicated section in NEW Show the exchange difference and allow re-aligning the invoice rate (option MULTICURRENCY_PAYMENT_USE_REAL_AMOUNTS) #39667.

Tested

Supplier and customer flows on real USD/TWD invoices: payment recorded with the real amounts, per-invoice derived rate stored, paid status set from the foreign balance, residual company-currency amount visible as the exchange difference.
Here is a screenshot:

Here are the tooltip and sublines orders screenshots: