Improve docs for solver API: limit amounts vs full amounts

docs/cow-protocol/reference/core/auctions/schema.md

@@ -76,8 +76,12 @@ This key maps to a list containing the set of orders in the batch. Each entry in
 - `uid`: this is the unique identifier of the order.
 - `sellToken`: a string denoting the address of the sell token.
 - `buyToken`: a string denoting the address of the buy token.
-- `sellAmount`: a stringified integer denoting the limit amount that is being sold, measured in terms of the smallest denomination of the sell token.
-- `buyAmount`: a stringified integer denoting the limit amount that is being bought. Similar to the `sellAmount`, it is measured in terms of the smallest denomination of the buy token.
+- `sellAmount`: a stringified integer denoting the sell amount that solvers should use when computing a solution, measured in terms of the smallest denomination of the sell token. This can differ from `fullSellAmount` (the order's original, signed sell amount) for two reasons:
+  1. For a partially fillable order that has already been (partly) filled in a previous auction, `sellAmount` is reduced to the *remaining*, unfilled amount, i.e., it already accounts for the `executed` amount.
+  2. For essentially every order, `sellAmount` is additionally scaled down to account for any volume-based protocol/partner fee (see `protocolFees`) that will be charged on top of the solution. It is chosen such that, once the driver charges that fee, the amount ultimately taken from the user still respects the order's original limit, `fullSellAmount`. This lets solvers compute solutions using `sellAmount` directly and ignore fees entirely, while the driver applies protocol/partner fees afterwards without violating the user's signed limit price.
+- `buyAmount`: analogous to `sellAmount`, but for the buy side: a stringified integer, measured in terms of the smallest denomination of the buy token, that reflects both the remaining unfilled amount (for partially filled orders) and any volume-fee adjustment relative to `fullBuyAmount`.
+- `fullSellAmount`: a stringified integer denoting the *original*, full limit sell amount of the order as signed by the user, measured in terms of the smallest denomination of the sell token. Unlike `sellAmount`, this value is never reduced for a previously executed amount nor adjusted for volume fees, so it stays constant across auctions for the same order and represents the limit that the driver must not violate once fees are charged.
+- `fullBuyAmount`: a stringified integer denoting the *original*, full limit buy amount of the order as signed by the user, measured in terms of the smallest denomination of the buy token. Unlike `buyAmount`, this value is never reduced for a previously executed amount nor adjusted for volume fees, so it stays constant across auctions for the same order and represents the limit that the driver must not violate once fees are charged.
 - `created`: creation time of the order, denominated in epoch seconds.
 - `validTo`: integer indicating the time until which the order is valid.
 - `kind`: a string of the set {"sell", "buy"}, describing whether the order is a `sell` or `buy` order.
@@ -107,14 +111,16 @@ An example Fill-or-Kill user limit buy order that sells 1000 [COW](https://ether
     "buyToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
     "sellAmount": "1000000000000000000000",
     "buyAmount": "284138335",
+    "fullSellAmount": "1000000000000000000000",
+    "fullBuyAmount": "284138335",
     "feeAmount": "0",
     "kind": "sell",
     "partiallyFillable": false,
     "class": "limit"
 }
 ```
 
-The above entry should be interpreted as follows. It is a Fill-or-Kill order since the flag `partiallyFillable` is set to `false`. Moreover, it is a sell order since its `kind` is set to `sell`. Finally, this is a `limit` order, meaning that it has a zero-signed fee, which implies that the solver is free to choose an appropriate fee to cover its execution cost. This means that, if executed, the user will send a total of 1000000000000000000000 COW atoms to the settlement contract and, no matter how much fee the solver will charge, the user is guaranteed to receive at least 284138335 USDC atoms.
+The above entry should be interpreted as follows. It is a Fill-or-Kill order since the flag `partiallyFillable` is set to `false`. Moreover, it is a sell order since its `kind` is set to `sell`. Finally, this is a `limit` order, meaning that it has a zero-signed fee, which implies that the solver is free to choose an appropriate fee to cover its execution cost. This means that, if executed, the user will send a total of 1000000000000000000000 COW atoms to the settlement contract and, no matter how much fee the solver will charge, the user is guaranteed to receive at least 284138335 USDC atoms. In this particular example `sellAmount`/`buyAmount` coincide with `fullSellAmount`/`fullBuyAmount` because the order has not been partially filled and has no `protocolFees` applied. In general, the two pairs will differ: `sellAmount`/`buyAmount` shrink further whenever an order is partially filled across auctions, and are also scaled relative to `fullSellAmount`/`fullBuyAmount` whenever a volume-based protocol/partner fee applies (which is the case for nearly all orders), so that the driver can charge that fee on top of a solver's solution without ever exceeding the user's originally signed limit.
 
 
 ### `deadline`