Refs #32013 -- Added backward incompatibility note about ModelChoiceIterator changes.

docs/ref/forms/fields.txt

@@ -1439,7 +1439,9 @@ customize the yielded 2-tuple choices.
 
             In older versions, the first ``value`` element in the choice tuple
             is the ``field`` value itself, rather than a
-            ``ModelChoiceIteratorValue`` instance.
+            ``ModelChoiceIteratorValue`` instance. In most cases this proxies
+            transparently but, if you need the ``field`` value itself, use the
+            :attr:`ModelChoiceIteratorValue.value` attribute instead.
 
 ``ModelChoiceIteratorValue``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/releases/3.1.txt

@@ -724,6 +724,14 @@ Miscellaneous
   without the ``type`` attribute to follow `WHATWG recommendations
   <https://html.spec.whatwg.org/multipage/scripting.html#the-script-element>`_.
 
+* :class:`~django.forms.ModelChoiceIterator`, used by
+  :class:`~django.forms.ModelChoiceField` and
+  :class:`~django.forms.ModelMultipleChoiceField`, now yields 2-tuple choices
+  containing :class:`~django.forms.ModelChoiceIteratorValue` instances as the
+  first ``value`` element in each choice. In most cases this proxies
+  transparently, but if you need the ``field`` value itself, use the
+  :attr:`.ModelChoiceIteratorValue.value` attribute instead.
+
 .. _deprecated-features-3.1:
 
 Features deprecated in 3.1