docs: clarify byte-budget gate covers slow-consumer cases too

Author: JanKaul

datafusion/physical-plan/src/repartition/distributor_channels.rs

@@ -40,7 +40,8 @@
 //! 1. *Gate A* — every output channel has at least one buffered item. This is the earliest legitimate backpressure
 //!    point: every consumer has work to do, so throttling the producer is safe.
 //! 2. *Gate B* — total in-memory bytes buffered across all channels reaches the configured `max_buffered_bytes`. This
-//!    bounds memory under skewed fan-out, where Gate A would never fire because some channel is always empty.
+//!    bounds memory whenever some channel is always empty, e.g. skewed fan-out, or even balanced fan-out where one
+//!    consumer lags: the producer keeps adding to the slow channel each round Gate A briefly opens.
 //!
 //! While the gate is closed, sender futures are [pending](Poll::Pending) until either a receiver drains an item or
 //! enough bytes are released to reopen the gate.

datafusion/physical-plan/src/repartition/mod.rs

@@ -1524,7 +1524,8 @@ impl RepartitionExec {
                         };
 
                     // Spilled markers occupy ~no in-channel memory; only count Memory variants against the gate's
-                    // byte budget.
+                    // byte budget. `size` may over-count for shared buffers (e.g. dictionary values across hash
+                    // partitions); over-counting is conservative — it just blocks producers slightly earlier.
                     let send_bytes = if is_memory_batch { size } else { 0 };
 
                     if channel